Static MorphIT

In the normal MorphIT mode each connected browser is assigned exactly one ClassiX instance until either browser or ClassiX is closed. If no ClassiX is available, the client is put into a queue and the user has to wait until an instance is restarted or released again.

The MorphIT server offers a static mode, in which previously exported static views with limited interactivity can be used even without a connected ClassiX. This relieves the server of simple page requests and does not limit the access to static content by the number of ClassiX processes.

Functionality

Before setting up the static mode, it is important to understand how it works, as the technical implementation and security aspects have some implications for the application.

Static Views

The MorphIT client detects that the static mode is active when loading. In this case no web socket connection to the MorphIT server is established (the server prevents this in static mode anyway), but an HTTP GET request with the path /view/0 is triggered. The server answers with the initial view, which is treated by the client as if it came from a ClassiX instance and represents the user interface.

In addition to the regular views, values, options, these static views contain an event map that defines the action behind each triggerable event. Normally a SELECT-event leads to a new view being opened. Each view is assigned an ID and each view can be requested via /view/ID. For navigation between views no running ClassiX instance is necessary, a running MorphIT server that delivers the statically exported views is sufficient.

Webservice Events

With purely static views, the static mode resembles primitive HTML pages that are linked together. Since, at the latest for login and thus the change to the dynamic mode (linked to a ClassiX instance), interactivity with ClassiX is required that cannot be exported statically, any interactivity on the static pages is traced back to HTTP POST web service requests. The web service requests are served by special ClassiX instances (number configurable), which are specifically reserved by the MorphIT server and are not coupled with regular MorphIT connections. The application can be easily scaled by the number of web service instances to be used.

Web service requests are sent by the MorphIT server via the connected web socket to the ClassiX instance and there they are handled via the regular web service interface and the response is sent via the web socket to the server and then as HTTP response to the client.

If the static views were exported in multiple languages, the client sends the currently activated language(x-morphit-language) and the UTC offset(x-morphit-utc-offset) in the HTTP header with every web service request. These headers are then also available in ClassiX, so that the web service can answer in the language of the client and convert data correctly.

WebWidgets

The webwidgetCommunication service used for web widgets recognises that the client is running in static mode and automatically sends all web widget messages as web service requests to the server. To support a web widget in static mode, ClassiX has to react to the corresponding web service requests in the same way as the web widget.

To decide which data should be displayed in the WebWidget, the export slot can be set to wwPrefix=pre when exporting in the WebWidget. This would prefix all WebWidget requests of this widget with the prefix PRE_ (example: PRE_GET_ROOT_POST). By using different prefixes, several WebWidgets of the same type can be supported, which work on different data.

Widgets

Regular widgets that do not open a view (example: login button) are also implemented through web service requests. In order for this to work automatically, the widgets have to be marked accordingly via the export slot and ClassiX has to respond to the request correctly. More about this here.

Direct links

In dynamic mode, a direct link first establishes a connection to a ClassiX and then executes the _AUTO message in this ClassiX. Since in static mode only authenticated users are allowed to receive a ClassiX instance, a special web service request is made beforehand VALIDATE_AUTO_POST, in which the web service instance can check beforehand whether the passed token/URL are valid and a ClassiX should be assigned to the client (response type: "dynamic"), or not (response type: "error", other).

If the request is valid, then VALIDATE_AUTO_POST should return the same JSON that was passed in the body of the request and additionally set the type field in the JSON to "dynamic". The JSON body of the request object has the following format:

Flow chart - direct link

Answer types

For web service requests through regular widgets and direct links, special responses are defined which are interpreted by the client and thus allow more interaction.

Error

Errors are displayed by the MorphIT client in an error dialogue box which can be closed with OK and the current view is not changed. After clicking away the error, work can be continued normally.

Attention

This response is handled by the client in a similar way to error, but the displayed dialogue box can be better designed. Due to the stateless communication, the ClassiX cannot respond to which button was pressed.

Login / Dynamic

If ClassiX responds with a login or dynamic type response, the MorphIT server automatically reserves a unique websocket endpoint for the client and places the endpoint ID in the response before it is forwarded to the client. The client then automatically connects to this endpoint, which allows exactly one connection and then becomes invalid. The server accepts the websocket connection and connects the client to a free ClassiX instance, or queues it. The client then switches to dynamic mode.

To enable a full login, there is a small difference between login and dynamic. If the web service responds with login, the MorphIT client must resend the request parameters of the corresponding web service request (usually the login data) in the auto parameters. This way the assigned ClassiX instance can perform a complete login.

The flowcharts of static login and static direct link hardly differ.

Flowchart - Static login

Redirect

With this response ClassiX can make the client load a certain static view (can also be a view alias ). This way the client can be redirected to a certain view in response to a web service request instead of giving the user feedback via attention/error.

UpdateView

4.1.0

This response type allows you to write an interactive application even in static mode.
All fields of this message are optional and can be combined as desired. Widgets to be modified are always referenced in this message by their parameter names, not by the widget ID. In order for this message to be processed correctly, it is important that the same parameter names are not assigned more than once within a view.

Example:
The following JSON sets the validation state for two widgets, fills the email widget with a dummy text and unchecks the checkbox and unlocks a button.

{
    "type":"update_view",

    "validation": {
        "email":{
            "level": "error",
            "text": "Email must be filled out!"
        },
        "comment": {
            "level": "info",
            "text": "A comment may be helpful"
        }
    },

    "values": {
        "email":"example@host.tld",
        "confirmCheckbox": false
    },

    "views": {
        "resetButton": {
            "locked": false
        }
    }
}

Example:
The following JSON redirects the client to the login page, focuses the widget with the parameter name "userID" and displays a dialog informing the user that the registration was successful.

{
  "type":"update_view",
  "redirect":"login",
  "focus":"userID",
  "dialog":{
      "level":"info",
      "text":"Registration successful"
  }
}

Static export

Before the static mode can be used, the static views must first be created. For this purpose, MorphIT offers an automated crawler that automatically walks through all accessible views, links them with each other and then downloads them. The crawler is accessible via the DesignMode menu(only active if design_mode_enabled=true is set in the configuration) (button:"Dump views"). During the export, the MorphIT server must still be running in non-static mode(static.enabled=false), otherwise the button is not displayed either.

This first opens the export overlay, which prevents interaction with the interface during export. Here you will also find settings for the export, a button to start the export and a log, which allows a diagnosis in case of export errors.

Preparation

Before exporting, you need to understand how static export works. Starting from the start-view, unknown events are triggered until the export knows which event leads to which view. Events of HIDDEN, LOCKED or NON_SELECTABLE widgets are ignored. If ClassiX triggers an error or attention during the export, the export is aborted. The automatic export does not fill in any fields, it only triggers SELECT. To export static views with interactivity, some widgets have to be provided with additional information by setting special slot values for the static export.

Since the crawler triggers each event once from each view, the duration of the export increases very quickly with the increasing number of events/views. In the export overlay there are settings that visualise the export better, but slow it down considerably for longer runs. The default settings guarantee the fastest export.

Widget Slots

If the SELECT event on the widget should lead to a web service request, then the slot key action must be defined on the triggering widget and parameters on the parameters to be transmitted. The following is an example of a login mask:

String(userStr, 0, 0, 100)
[ INITIALIZE: "parameter=username" Widget Put(morphIt.externalID) ]

String(passStr, PASSWORD, 0, 10, 100)
[ INITIALIZE: "parameter=password" Widget Put(morphIt.externalID) ]

Button(login, 0, 20, 100, 8)
[ INITIALIZE: "action=login_static" Widget Put(morphIt.externalID)
  SELECT: DoRegularLogin
]

When exporting, the crawler will not trigger the SELECT event on the button, but will note in the view that a web service is to be triggered when a SELECT occurs. The parameter fields are transferred as JSON objects in the HTTP body. Query parameters that are set in the client are also transferred as query parameters in the HTTP request object and are available in the web service.
If the MorphIT server runs under HTTPS (recommended!), then the web service requests are also made over HTTPS and their content is therefore encrypted and cannot be read by third parties. This web service must be programmed in ClassiX afterwards:

Msg(LOGIN_STATIC_POST) // will be send to webservice instance first
LOGIN_STATIC_POST: {
  LocalVar(reqjs, name, pw)
  Call(GetBody) jsonTools::LoadFromString -> reqjs //parse body

  reqjs Copy(username) -> name
  reqjs Copy(password) -> pw

  // result if login doesn't match
  "{\"type\":\"error\", \"error\":\"Wrong username/password passed!\"}" jsonTools::LoadFromString -> result

  // very simplified login check
  name "admin" = pw "pass" = & if {
     // login successful
     CreateTransObject(CX_JSON_OBJECT) -> result
     "login" result Put(type)               //response type = "login"
     "login_static" result Put(auto)        //client should trigger LOGIN_STATIC_AUTO
   }

   // return response
   result ReturnStack
}

Msg(LOGIN_STATIC_AUTO) // will be send to assigned instance
LOGIN_STATIC_AUTO: {
  LocalVar(loginjs, name, pw)
  jsonTools::LoadFromString -> loginjs

  // Because we have answered with type="login" we get the same login parameters again
  // If we had answered with type="dynamic" then we wouldn't have access to the same parameters
  loginjs Copy(username) -> name
  loginjs Copy(password) -> pw

  // recheck login to be safe
  name "admin" = pw "pass" = & if {
    // actually login user with that user/password
    ...
  } else {
    // We can open an attention here, because this is the connected ClassiX instance
    "Invalid login data!" Attention(,ERROR)
    TerminateApp
  }
}

The login example given here is for illustration purposes only. In the concrete implementation, care should be taken that the login token can only be used once and expires after a finite time, so that valid (unused) tokens cannot be guessed by an attacker by trial and error. This time should not be chosen too short, if more users use the system than ClassiX processes can be started. The client would be put into a queue after login and would use the login token only when a ClassiX instance becomes free. If the token expires in the meantime, the user has to log in again. To prevent this, a timeout of about 5-10 minutes should be selected.

The process of a static login (with other messages) is illustrated in the following flow chart.

Flowchart - Static login

Widgets whose SELECT event not only leads to a new view and cannot be mapped to web services can be hidden in the exported view as follows:

[ INITIALIZE: "hidden=true" Widget Put(morphIt.externalID) ]

Slot values

For export purposes, widgets can be provided with additional semantics via the slot morphIt.externalID. The slot is a string with the syntax: key=value;key=value;key=value
Keys are not case-sensitive.

The following keys are defined:

WebWidgets

In order for web widgets in static mode to work as well, _POST messages with the same name (in the module) must be handled in addition to the _SOCKET messages of the web widgets that have been usual up to now. The WebWidget should not be opened for processing the messages in order to avoid bringing a state into the web service instance and the instance cannot rely on the fact that the WebWidgets have been filled with data by a previous event (each request must be self-contained).

If several WebWidgets of the same type (with different data/settings) are to be used in a static application, the wwPrefix key can be used to define a prefix that precedes each message of this WebWidge so that the message indicates which WebWidge is requesting data. Example (Organigram):

Web(...)
[ INITIALIZE: "wwPrefix=abc" Widget Put(morphIt.externalID) ]

Web(...)
[ INITIALIZE: "wwPrefix=test" Widget Put(morphIt.externalID) ]

Msg(ABC_GET_ROOT, TEST_GET_ROOT)
ABC_GET_ROOT: //...
TEST_GET_ROOT: //...

CAPTCHAs

4.1.1

MorphIT offers the possibility to easily integrate reCAPTCHA in static mode to prevent access to certain web services by bots and thus possible DOS attacks. The user must first be identified by CAPTCHA as a real user before the web service request is passed on to ClassiX. As CAPTCHAS serve to protect access to ClassiX resources against unauthorized access, they are only implemented in static mode, as an existing MorphIT connection assumes that the user is already authorized.

Requirements:

• Google account
• MorphIT server and MorphIT clients have an Internet connection

To integrate a CAPTCHA in MorphIT, a Google account must first be created and a reCAPTCHA (version 2) registered for the server. All hostnames/domains through which the MorphIT server should be accessible for clients should be entered as hostnames. For a purely local use localhost must be entered. With the registration of the reCAPTCHA you receive a site key and a secret key. These keys must be entered in the server configuration under static.captcha.secret_key and static.captcha.site_key . Now the server is prepared.

Before the static export, a placeholder widget (e.g. a button) must now be defined for the CAPTCHA, which is replaced by the CAPTCHA in the exported state. The widget can be HIDDEN in normal mode and can be made visible only for static export via the export slot hidden=false. The size of the widget is ignored, because the static export uses the optimal size (300 x 75 pixels) for this.

Example code:

Button(captchaBtn, HIDDEN, 100, 11, 200, 7, "CAPTCHA")
[ INITIALIZE: "captcha=CREATE_USER_CLOUD_ACCOUNT_STATIC;hidden=false" Widget Put(morphIt.externalID) ]

Button(OKBtn, LOCKED, 200, 11, 200, 7, T("&Speichern", "&Save"))
[ INITIALIZE: "call_to_action" Widget Put(morphIt.drawingID)
              "action=CREATE_USER_CLOUD_ACCOUNT_STATIC;locked=false" Widget Put(morphIt.externalID)

  SELECT: SaveObject
          Drop
]

Attach(OKBtn, RIGHT, 15)
Attach(captchaBtn, OKBtn, RIGHT, OPPOSITE, 100)

Declaration:

1. The OKBtn triggers the web service CREATE_USER_CLOUD_ACCOUNT_STATIC in static mode, therefore captcha=CREATE_USER_CLOUD_ACCOUNT_STATIC must also be set in the captcha widget. Thereby the CAPTCHA is linked to the button.
2. The OKBtn is normally locked and is only unlocked by the input validation (ALTERED). Because the static mode does not support an ALTERED event, the button must always be unlocked, this is done with locked=false.
3. So that the captcha widget does not disturb in regular operation, it is HIDDEN and is made visible for static export via hidden=false.

If the interface contains at least one CAPTCHA during static export, then an additional captcha_webservices.json is downloaded together with the remaining views when the export is completed. This file should be exported together with the views into the same directory and is used by the MorphIT server to determine which webservice requests must be verified by a CAPTCHA and which not. If this file is missing, then no CAPTCHAs are verified by the server and all requests can theoretically be executed without solving a captcha.

reCAPTCHA delivers a token upon successful confirmation, which is transmitted in the x-morphit-captcha HTTP header in the web service request to the MorphIT server and can be verified once by the server. Webservice requests for webservices declared in captcha_webservices.json and sent with an invalid token or missing token are rejected by the MorphIT server with an error message and ClassiX does not notice these requests.

Result:

Direct links

If direct links are to be supported in static mode, the message VALIDATE_AUTO_POST must be defined as described here .

Alias Views

If the client should be able to jump to a certain mask in static mode (before login) via a certain URL (example: open login mask directly), then after the static export a redirection from a freely selectable identifier to the view to be opened must be set up for the view to be reached.

The easiest way to generate this redirection is via the design mode. If the server is started instatic mode(static.enabled=true), the button"Alias view" appears in the design mode menu. This button first asks for an alias name for the current view and then generates a redirection file which the browser automatically downloads. This file must be placed in the same directory as the automatically exported views of the static export for the alias to work.

For example, if you navigate to the login mask and set the alias name to login, the browser will download a login_view.json, which contains a redirection to the actual view. If you copy this file into the directory from which the server loads the views, you can jump directly to the login mask in the client using the URL query ?view=login.

If the ID of the view is known, you can also jump to view 9_view.json via ?view=9. Since the IDs depend on the order of the events in the export process, it is recommended and more memorable to assign alias names for them. The fact that the IDs can change also means that the redirection files potentially have to be recreated (or at least checked) after each export.

Script-controlled export

4.1.3

The script-controlled MorphIT export is a possibility to further automate the static export and to export even more complicated applications. In this case an export script is dropped into the export overlay (a JavaScript file) before the export and this script can control the export to a certain extent.

The script can react to events during the export and influence the export as follows:

• Evaluate views & cancel export with error message
• Trigger events on the current view and continue the export on another view
• Display simple dialogues
• Examine the current export status and define alias views

The following example script is a complex example of what is currently possible with the export script. The script exports two applications one after the other and defines alias views so that the alias views can be used to navigate between the individual applications later.

This script:

1. Checks whether the correct application has started using the MorphIT properties before export(onExportStart)
2. Defines 2 alias views after export(onExplorationEnd) by checking which views were reached by clicking on certain widgets
3. Represents a dialogue that gives instructions to the user
4. Closes the currently connected ClassiX application and confirms the confirmation request(onAttention)
5. Checks, using the MorphIT properties, whether the new instance is the expected one.
6. Defines an alias for this new view and continues the export from there.

Code: (export-script.js)

/** This script is the export script for the cloud application.
 *  It will:
 *     - define the alias views 'login', 'register' and 'login_direct'
 *     - guide the user to correctly export the regular portal login views and the product login view
 */

events.onExportStart = function(firstView) {
    var properties = firstView.view.options.properties;
    if (properties.project !== 'classix.cloud' || properties.project_type !== undefined) {
        throw new Error("The selected export script is incompatible with the currently connected ClassiX instance! This export script has been written for classix.cloud portal application!");
    }
};


// Return true or a promise, which resolves to true to rerun the exploration.
// The passed view will be an ActiveView on which an event can be triggered. All other views are accessible through exportContext.view(id)
events.onExplorationEnd = function(lastView) {

    // Define login alias
    var initialView = exportContext.view(0);
    var loginItemId = initialView.findWidget(function(widget)  { return _.get(widget, 'slots.number') === 'UserIcon'; });
    var loginViewId = initialView.findEvent(function(event) { return event.id === loginItemId; }).action.view;
    exportContext.defineAlias(loginViewId, 'login');


    // Define register alias
    var registerViewId = exportContext.view(loginViewId).findEvent(function(event) {
        return event.event === 'SELECT@new'; // This is how we detect the register link
    }).action.view;
    exportContext.defineAlias(registerViewId, 'register');


    //////////////
    // Now prepare changing the application to export the product login view
    //////////////

    // Register an attention handler here because the ClassiX instance will want to know whether we really want to shut it down
    // and we don't want to error there and simply confirm this dialog.
    var oldAttentionHandler = events.onAttention;
    events.onAttention = function(attention) {
        attention.clickButton(attention.buttons[0]);
        events.onAttention = oldAttentionHandler;
    };

    // Show a dialog with further instructions for the user before closing the application
    showDialog('Information', "The export of the cloud portal views has been completed and ClassiX closed.\n" +
        "Please start the cloud product login application to continue exporting the product login views.");

    var controlWin = lastView.findWidget(function(widget) { return widget.control_window === true; });
    return controlWin.close().then(function(currentView) {
        // The promise gets completed as soon as the client reconnects to the next ClassiX instance.
        // The view hasn't yet been processed by the static export and has thus no id.

        // We set the project_type property to 'client_login' to mark the expected application as such
        if (currentView.view.options.properties.project_type !== 'client_login') {
            throw new Error("Export script expected a different application to connect to. Client login application hasn't been recognized.");
        }

        hideDialog();

        // The next time exploration has completed, we are done
        events.onExplorationEnd = function() { return false; };

        // Define an alias for this view
        exportContext.defineAlias(exportContext.nextViewId(), 'login_direct');

        // continue exploration from this new view
        return true;
    });
};

script events:

onExportStart(activeView :ActiveView) : { bool | Promise }

This function is called before the export with the currently loaded view. The function can trigger events and thus change the initial view. When the function is finished and the export is to be started, it should return true to tell the export that the active view has changed and the view must be reloaded (via load_view message). If it returns false , then the export assumes that the view has not been changed.
If the function works asynchronously (loads views), it can also return a promise to true or false. The export then waits for the asynchronous operation to complete before starting the export.

The export can be stopped completely by throwing an error in this function. The error is displayed in the export status window and the export is not started.

onAfterNormalization(normalizedView :View, originialView) : View

"instances":[
  {
    "id":"login",
    "path":"/login"
  },
  {
    "path":"/long_running_task",
    "launch": {
      "cmd":"task_webservice_runner.bat"
    }
  },
  {
    "id":"default",
    "instances":2
  },
  {
    "id":"worker",
    "parameters":["do","important","work!"],
    "instances":2,
    "registration_webservice":"start_worker"
  }
]

{
  "id":"worker",
  "parameters":["do","important","work!"],
  "instances":2,
  "registration_webservice":"start_worker"
}